<!DOCTYPE html>
<html lang="en-us">
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    
<meta charset="UTF-8">
<title>Aggregation Test-Drive | Elasticsearch: The Definitive Guide [2.x] | Elastic</title>
<link rel="home" href="index.html" title="Elasticsearch: The Definitive Guide [2.x]">
<link rel="up" href="aggregations.html" title="Aggregations">
<link rel="prev" href="_combining_the_two.html" title="Combining the Two">
<link rel="next" href="_adding_a_metric_to_the_mix.html" title="Adding a Metric to the Mix">
<meta name="DC.type" content="Learn/Docs/Legacy/Elasticsearch/Definitive Guide/2.x">
<meta name="DC.subject" content="Elasticsearch">
<meta name="DC.identifier" content="2.x">
<meta name="robots" content="noindex,nofollow">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd">
    <meta name="yandex-verification" content="d8a47e95d0972434">
    <meta name="localized" content="true">
    <meta name="st:robots" content="follow,index">
    <meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles.css">
  </head>

  <!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
    <script type="text/javascript">
      (function(){var g=function(e,h,f,g){
      this.get=function(a){for(var a=a+"=",c=document.cookie.split(";"),b=0,e=c.length;b<e;b++){for(var d=c[b];" "==d.charAt(0);)d=d.substring(1,d.length);if(0==d.indexOf(a))return d.substring(a.length,d.length)}return null};
      this.set=function(a,c){var b="",b=new Date;b.setTime(b.getTime()+6048E5);b="; expires="+b.toGMTString();document.cookie=a+"="+c+b+"; path=/; "};
      this.check=function(){var a=this.get(f);if(a)a=a.split(":");else if(100!=e)"v"==h&&(e=Math.random()>=e/100?0:100),a=[h,e,0],this.set(f,a.join(":"));else return!0;var c=a[1];if(100==c)return!0;switch(a[0]){case "v":return!1;case "r":return c=a[2]%Math.floor(100/c),a[2]++,this.set(f,a.join(":")),!c}return!0};
      this.go=function(){if(this.check()){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)}};
      this.start=function(){var a=this;window.addEventListener?window.addEventListener("load",function(){a.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){a.go()})}};
      try{(new g(100,"r","QSI_S_ZN_emkP0oSe9Qrn7kF","https://znemkp0ose9qrn7kf-elastic.siteintercept.qualtrics.com/WRSiteInterceptEngine/?Q_ZID=ZN_emkP0oSe9Qrn7kF")).start()}catch(i){}})();
    </script><div id="ZN_emkP0oSe9Qrn7kF"><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
    <!--END WEBSITE FEEDBACK SNIPPET-->

    <div id="elastic-nav" style="display:none;"></div>
    <script src="https://www.elastic.co/elastic-nav.js"></script>

    <!-- Subnav -->
    <div>
      <div>
        <div class="tertiary-nav d-none d-md-block">
          <div class="container">
            <div class="p-t-b-15 d-flex justify-content-between nav-container">
              <div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="main-container">
      <section id="content">
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container">
              <div class="row">
                <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                  <!-- start body -->
                  <div class="page_header">
<p>
  <strong>WARNING</strong>: The 2.x versions of Elasticsearch have passed their
  <a href="https://www.elastic.co/support/eol">EOL dates</a>. If you are running
  a 2.x version, we strongly advise you to upgrade.
</p>
<p>
  This documentation is no longer maintained and may be removed. For the latest
  information, see the <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html">current
  Elasticsearch documentation</a>.
</p>
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch: The Definitive Guide [2.x]</a></span>
»
<span class="breadcrumb-link"><a href="aggregations.html">Aggregations</a></span>
»
<span class="breadcrumb-node">Aggregation Test-Drive</span>
</div>
<div class="navheader">
<span class="prev">
<a href="_combining_the_two.html">« Combining the Two</a>
</span>
<span class="next">
<a href="_adding_a_metric_to_the_mix.html">Adding a Metric to the Mix »</a>
</span>
</div>
<div class="chapter">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="_aggregation_test_drive"></a>Aggregation Test-Drive<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch-definitive-guide/edit/2.x/300_Aggregations/20_basic_example.asciidoc">edit</a>
</h2>
</div></div></div>
<p>We could spend the next few pages defining the various aggregations
and their syntax, but aggregations are truly best learned by example.
Once you learn how to think about aggregations, and how to nest them appropriately,
the syntax is fairly trivial.</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>A complete list of aggregation buckets and metrics can be found at the <a href="/guide/en/elasticsearch/reference/2.4/search-aggregations.html" class="ulink" target="_top">Elasticsearch Reference</a>.  We’ll cover many of them in this chapter, but glance
over it after finishing so you are familiar with the full range of capabilities.</p>
</div>
</div>
<p>So let’s just dive in and start with an example.  We are going to build some
aggregations that might be useful to a car dealer.  Our data will be about car
transactions: the car model, manufacturer, sale price, when it sold, and more.</p>
<p>First we will bulk-index some data to work with:</p>
<div class="pre_wrapper lang-sense">
<pre class="programlisting prettyprint lang-sense">POST /cars/transactions/_bulk
{ "index": {}}
{ "price" : 10000, "color" : "red", "make" : "honda", "sold" : "2014-10-28" }
{ "index": {}}
{ "price" : 20000, "color" : "red", "make" : "honda", "sold" : "2014-11-05" }
{ "index": {}}
{ "price" : 30000, "color" : "green", "make" : "ford", "sold" : "2014-05-18" }
{ "index": {}}
{ "price" : 15000, "color" : "blue", "make" : "toyota", "sold" : "2014-07-02" }
{ "index": {}}
{ "price" : 12000, "color" : "green", "make" : "toyota", "sold" : "2014-08-19" }
{ "index": {}}
{ "price" : 20000, "color" : "red", "make" : "honda", "sold" : "2014-11-05" }
{ "index": {}}
{ "price" : 80000, "color" : "red", "make" : "bmw", "sold" : "2014-01-01" }
{ "index": {}}
{ "price" : 25000, "color" : "blue", "make" : "ford", "sold" : "2014-02-12" }</pre>
</div>
<div class="sense_widget" data-snippet="snippets/300_Aggregations/20_basic_example.json"></div>
<p>Now that we have some data, let’s construct our first aggregation.  A car dealer
may want to know which color car sells the best.  This is easily accomplished
using a simple aggregation.  We will do this using a <code class="literal">terms</code> bucket:</p>
<div class="pre_wrapper lang-sense">
<pre class="programlisting prettyprint lang-sense">GET /cars/transactions/_search
{
    "size" : 0,
    "aggs" : { <a id="CO185-1"></a><i class="conum" data-value="1"></i>
        "popular_colors" : { <a id="CO185-2"></a><i class="conum" data-value="2"></i>
            "terms" : { <a id="CO185-3"></a><i class="conum" data-value="3"></i>
              "field" : "color"
            }
        }
    }
}</pre>
</div>
<div class="sense_widget" data-snippet="snippets/300_Aggregations/20_basic_example.json"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO185-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>Aggregations are placed under the top-level <code class="literal">aggs</code> parameter (the longer <code class="literal">aggregations</code>
will also work if you prefer that).</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO185-2"><i class="conum" data-value="2"></i></a></p>
</td>
<td align="left" valign="top">
<p>We then name the aggregation whatever we want: <code class="literal">popular_colors</code>, in this example</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO185-3"><i class="conum" data-value="3"></i></a></p>
</td>
<td align="left" valign="top">
<p>Finally, we define a single bucket of type <code class="literal">terms</code>.</p>
</td>
</tr>
</table>
</div>
<p>Aggregations are executed in the context of search results, which means it is
just another top-level parameter in a search request (for example, using the <code class="literal">/_search</code>
endpoint).  Aggregations can be paired with queries, but we’ll tackle that later
in <a class="xref" href="_scoping_aggregations.html" title="Scoping Aggregations"><em>Scoping Aggregations</em></a>.</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>You’ll notice that we set the <code class="literal">size</code> to zero. We
don’t care about the search results themselves and
returning zero hits speeds up the query. Setting
<code class="literal">size: 0</code> is the equivalent of using the <code class="literal">count</code>
search type in Elasticsearch 1.x.</p>
</div>
</div>
<p>Next we define a name for our aggregation.  Naming is up to you;
the response will be labeled with the name you provide so that your application
can parse the results later.</p>
<p>Next we define the aggregation itself.  For this example, we are defining
a single <code class="literal">terms</code> bucket.  The <code class="literal">terms</code> bucket will dynamically create a new
bucket for every unique term it encounters.  Since we are telling it to use the
<code class="literal">color</code> field, the <code class="literal">terms</code> bucket will dynamically create a new bucket for each color.</p>
<p>Let’s execute that aggregation and take a look at the results:</p>
<div class="pre_wrapper lang-js">
<pre class="programlisting prettyprint lang-js">{
...
   "hits": {
      "hits": [] <a id="CO186-1"></a><i class="conum" data-value="1"></i>
   },
   "aggregations": {
      "popular_colors": { <a id="CO186-2"></a><i class="conum" data-value="2"></i>
         "buckets": [
            {
               "key": "red", <a id="CO186-3"></a><i class="conum" data-value="3"></i>
               "doc_count": 4 <a id="CO186-4"></a><i class="conum" data-value="4"></i>
            },
            {
               "key": "blue",
               "doc_count": 2
            },
            {
               "key": "green",
               "doc_count": 2
            }
         ]
      }
   }
}</pre>
</div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO186-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>No search hits are returned because we set the <code class="literal">size</code> parameter</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO186-2"><i class="conum" data-value="2"></i></a></p>
</td>
<td align="left" valign="top">
<p>Our <code class="literal">popular_colors</code> aggregation is returned as part of the <code class="literal">aggregations</code> field.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO186-3"><i class="conum" data-value="3"></i></a></p>
</td>
<td align="left" valign="top">
<p>The <code class="literal">key</code> to each bucket corresponds to a unique term found in the <code class="literal">color</code> field.
It also always includes <code class="literal">doc_count</code>, which tells us the number of docs containing the term.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO186-4"><i class="conum" data-value="4"></i></a></p>
</td>
<td align="left" valign="top">
<p>The count of each bucket represents the number of documents with this color.</p>
</td>
</tr>
</table>
</div>
<p>The response contains a list of buckets, each corresponding to a unique color
(for example, red or green). Each bucket also includes a count of the number of documents
that "fell into" that particular bucket.  For example, there are four red cars.</p>
<p>The preceding example is operating entirely in real time: if the documents are searchable,
they can be aggregated.  This means you can take the aggregation results and
pipe them straight into a graphing library to generate real-time dashboards.
As soon as you sell a silver car, your graphs would dynamically update to include
statistics about silver cars.</p>
<p>Voila!  Your first aggregation!
</p>



</div>
<div class="navfooter">
<span class="prev">
<a href="_combining_the_two.html">« Combining the Two</a>
</span>
<span class="next">
<a href="_adding_a_metric_to_the_mix.html">Adding a Metric to the Mix »</a>
</span>
</div>
</div>

                  <!-- end body -->
                </div>
                <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                  <div id="rtpcontainer" style="display: block;">
                    <div class="mktg-promo">
                      <h3>Most Popular</h3>
                      <ul class="icons">
                        <li class="icon-elasticsearch-white"><a href="https://www.elastic.co/webinars/getting-started-elasticsearch?baymax=default&amp;elektra=docs&amp;storm=top-video">Get Started with Elasticsearch: Video</a></li>
                        <li class="icon-kibana-white"><a href="https://www.elastic.co/webinars/getting-started-kibana?baymax=default&amp;elektra=docs&amp;storm=top-video">Intro to Kibana: Video</a></li>
                        <li class="icon-logstash-white"><a href="https://www.elastic.co/webinars/introduction-elk-stack?baymax=default&amp;elektra=docs&amp;storm=top-video">ELK for Logs &amp; Metrics: Video</a></li>
                      </ul>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


<div id="elastic-footer"></div>
<script src="https://www.elastic.co/elastic-footer.js"></script>
<!-- Footer Section end-->

      </section>
    </div>

<script src="/guide/static/jquery.js"></script>
<script type="text/javascript" src="/guide/static/docs.js"></script>
<script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>
